<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>pthread_attr_getguardsize</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_007_1135">&nbsp;</a>NAME</h4><blockquote>
pthread_attr_getguardsize, pthread_attr_setguardsize -
get or set the thread guardsize attribute
</blockquote><h4><a name = "tag_000_007_1136">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="pthread.h.html">pthread.h</a>&gt;

int pthread_attr_getguardsize(const pthread_attr_t <i>*attr</i>,
    size_t <i>*guardsize</i>);
int pthread_attr_setguardsize(pthread_attr_t <i>*attr</i>,
    size_t <i>guardsize</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_1137">&nbsp;</a>DESCRIPTION</h4><blockquote>
The <i>guardsize</i> attribute controls the size
of the guard area for the created thread's stack. The <i>guardsize</i>
attribute provides protection against overflow of the
stack pointer. If a thread's stack is created with guard
protection, the implementation allocates extra
memory at the overflow end of the stack as a buffer against
stack overflow of the stack pointer. If an application
overflows into this buffer an error results (possibly
in a SIGSEGV signal being delivered to the thread).
<p>
The <i>guardsize</i> attribute is provided to the application
for two reasons:
<ol type = 1>
<p>
<li>
Overflow protection can potentially
result in wasted system resources. An application that creates a large
number of threads, and which knows its threads will never overflow
their stack, can save system resources by turning off guard areas.
<p>
<li>
When threads allocate large data structures on the stack,
large guard areas may be needed to detect stack overflow.
<p>
</ol>
<p>
The 
<i>pthread_attr_getguardsize()</i>
function gets the
<i>guardsize</i> attribute in the <i>attr</i> object. This attribute is
returned in the <i>guardsize</i> parameter.
<p>
The 
<i>pthread_attr_setguardsize()</i>
function sets the
<i>guardsize</i> attribute in the <i>attr</i> object. The new value of
this attribute is obtained from the <i>guardsize</i> parameter.
If <i>guardsize</i> is zero, a guard area will not be
provided for threads created with <i>attr</i>. If <i>guardsize</i> is
greater
than zero, a guard area of at least size <i>guardsize</i>
bytes is provided for each thread created with <i>attr</i>.
<p>
A conforming implementation is permitted to round up
the value contained in <i>guardsize</i> to a multiple
of the configurable system variable PAGESIZE (see 
<i><a href="sysmman.h.html">&lt;sys/mman.h&gt;</a></i>).
If an implementation rounds up the
value of <i>guardsize</i> to a multiple of PAGESIZE, a call to
<i>pthread_attr_getguardsize()</i>
specifying <i>attr</i> will
store in the <i>guardsize</i> parameter the guard size specified by the
previous 
<i>pthread_attr_setguardsize()</i>
function call.
<p>
The default value of the <i>guardsize</i> attribute is PAGESIZE bytes.
The actual value of PAGESIZE is
implementation-dependent and may not be the same on all implementations.
<p>
If the <i>stackaddr</i> attribute has been set (that is, the caller
is allocating and managing its own thread stacks), the
<i>guardsize</i> attribute is ignored and no protection
will be provided by the implementation. It is the
responsibility of the application to manage stack overflow
along with stack allocation and management in this
case.
</blockquote><h4><a name = "tag_000_007_1138">&nbsp;</a>RETURN VALUE</h4><blockquote>
If successful, the 
<i>pthread_attr_getguardsize()</i>
and
<i>pthread_attr_setguardsize()</i>
functions return zero.
Otherwise, an error number is returned to indicate the error.
<br>
</blockquote><h4><a name = "tag_000_007_1139">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>pthread_attr_getguardsize()</i>
and
<i>pthread_attr_setguardsize()</i>
functions will fail if:
<dl compact>

<dt>[EINVAL]<dd>
The attribute <i>attr</i> is invalid.

<dt>[EINVAL]<dd>The parameter <i>guardsize</i> is invalid.

<dt>[EINVAL]<dd>The parameter <i>guardsize</i> contains an invalid value.

</dl>
</blockquote><h4><a name = "tag_000_007_1140">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1141">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1142">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1143">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="pthread.h.html">&lt;pthread.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
